Chapter 9: TypeScript in Practice

src/
├── components/
│   ├── ProductCard.jsx          ← Our migration target
│   ├── ProductList.jsx          ← Depends on ProductCard
│   └── ShoppingCart.jsx         ← Uses product data
├── utils/
│   ├── formatPrice.js           ← Utility functions
│   └── api.js                   ← API client
└── types/
    └── product.ts               ← We'll create this

// src/components/ProductCard.jsx
import React from 'react';
import { formatPrice } from '../utils/formatPrice';

export function ProductCard({ product, onAddToCart }) {
  const handleClick = () => {
    onAddToCart(product);
  };

  return (
    <div className="product-card">
      <img src={product.imageUrl} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <div className="price">
        {product.onSale && (
          <span className="original-price">
            {formatPrice(product.originalPrice)}
          </span>
        )}
        <span className="current-price">
          {formatPrice(product.price)}
        </span>
      </div>
      <button onClick={handleClick}>Add to Cart</button>
      {product.inStock === false && (
        <div className="out-of-stock">Out of Stock</div>
      )}
    </div>
  );
}

// src/utils/formatPrice.js
export function formatPrice(price) {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(price);
}

// src/utils/api.js
export async function fetchProducts() {
  const response = await fetch('/api/products');
  return response.json();
}

export async function addToCart(productId, quantity) {
  const response = await fetch('/api/cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ productId, quantity })
  });
  return response.json();
}

TypeError: Cannot read properties of null (reading 'toString')
  at ShoppingCart.validateInventory (ShoppingCart.jsx:45)
  at ShoppingCart.handleCheckout (ShoppingCart.jsx:78)

TypeError: Cannot read properties of null (reading 'toString')
  at ShoppingCart.validateInventory (ShoppingCart.jsx:45)
  at ShoppingCart.handleCheckout (ShoppingCart.jsx:78)
  at onClick (ShoppingCart.jsx:92)

// src/types/product.ts

/**
 * Core product data structure used throughout the application.
 * This type represents products from our API and database.
 */
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  imageUrl: string;
  inStock: boolean;  // ← Must be boolean, not null
  onSale?: boolean;  // ← Optional: only present when on sale
  originalPrice?: number;  // ← Optional: only present when on sale
}

/**
 * Type guard to validate unknown data is a valid Product.
 * Use this when receiving data from APIs or external sources.
 */
export function isProduct(data: unknown): data is Product {
  if (typeof data !== 'object' || data === null) {
    return false;
  }

  const obj = data as Record<string, unknown>;

  return (
    typeof obj.id === 'string' &&
    typeof obj.name === 'string' &&
    typeof obj.description === 'string' &&
    typeof obj.price === 'number' &&
    typeof obj.imageUrl === 'string' &&
    typeof obj.inStock === 'boolean' &&
    (obj.onSale === undefined || typeof obj.onSale === 'boolean') &&
    (obj.originalPrice === undefined || typeof obj.originalPrice === 'number')
  );
}

// src/components/ProductCard.tsx
import React from 'react';
import { formatPrice } from '../utils/formatPrice';
import { Product } from '../types/product';

interface ProductCardProps {
  product: Product;
  onAddToCart: (product: Product) => void;
}

export function ProductCard({ product, onAddToCart }: ProductCardProps) {
  const handleClick = () => {
    onAddToCart(product);
  };

  return (
    <div className="product-card">
      <img src={product.imageUrl} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <div className="price">
        {product.onSale && (
          <span className="original-price">
            {formatPrice(product.originalPrice!)}
          </span>
        )}
        <span className="current-price">
          {formatPrice(product.price)}
        </span>
      </div>
      <button onClick={handleClick}>Add to Cart</button>
      {product.inStock === false && (
        <div className="out-of-stock">Out of Stock</div>
      )}
    </div>
  );
}

npx tsc --noEmit

src/components/ProductCard.tsx:18:25 - error TS2532:
Object is possibly 'undefined'.

18           {formatPrice(product.originalPrice!)}
                           ~~~~~~~~~~~~~~~~~~~~~

src/utils/formatPrice.js:1:1 - error TS7016:
Could not find a declaration file for module '../utils/formatPrice'.
'/src/utils/formatPrice.js' implicitly has an 'any' type.

1 import { formatPrice } from '../utils/formatPrice';
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Found 2 errors.

// src/components/ProductCard.tsx (Fixed)
import React from 'react';
import { formatPrice } from '../utils/formatPrice';
import { Product } from '../types/product';

interface ProductCardProps {
  product: Product;
  onAddToCart: (product: Product) => void;
}

export function ProductCard({ product, onAddToCart }: ProductCardProps) {
  const handleClick = () => {
    onAddToCart(product);
  };

  return (
    <div className="product-card">
      <img src={product.imageUrl} alt={product.name} />
      <h3>{product.name}</h3>
      <p>{product.description}</p>
      <div className="price">
        {product.onSale && product.originalPrice !== undefined && (
          <span className="original-price">
            {formatPrice(product.originalPrice)}
          </span>
        )}
        <span className="current-price">
          {formatPrice(product.price)}
        </span>
      </div>
      <button onClick={handleClick}>Add to Cart</button>
      {product.inStock === false && (
        <div className="out-of-stock">Out of Stock</div>
      )}
    </div>
  );
}

// src/utils/formatPrice.ts
export function formatPrice(price: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(price);
}

npx tsc --noEmit

✓ No errors found

// src/components/ProductList.tsx
import { ProductCard } from './ProductCard';

function ProductList() {
  // This would have caused a runtime error in JavaScript
  const invalidProduct = {
    id: "123",
    name: "eBook",
    description: "A digital download",
    price: 9.99,
    imageUrl: "/ebook.jpg",
    inStock: null,  // ← TypeScript error!
  };

  return (
    <ProductCard 
      product={invalidProduct}  // ← Error here
      onAddToCart={(p) => console.log(p)}
    />
  );
}

src/components/ProductList.tsx:15:7 - error TS2322:
Type 'null' is not assignable to type 'boolean'.

15       inStock: null,
         ~~~~~~~

src/components/ProductList.tsx:19:7 - error TS2322:
Type '{ id: string; name: string; ...; inStock: null; }' is not assignable to type 'Product'.
  Types of property 'inStock' are incompatible.
    Type 'null' is not assignable to type 'boolean'.

19       product={invalidProduct}
         ~~~~~~~

{
  "id": "123",
  "name": "Laptop",
  "image_url": "laptop.jpg",  // ← Changed from imageUrl
  "price": 999.99,
  "inStock": true
}

GET http://localhost:3000/undefined 404 (Not Found)

// src/utils/api.ts
import { Product, isProduct } from '../types/product';

/**
 * Custom error for API validation failures.
 * Includes the invalid data for debugging.
 */
export class ValidationError extends Error {
  constructor(
    message: string,
    public readonly invalidData: unknown
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

/**
 * Fetch all products from the API.
 * Validates each product matches the Product type.
 * @throws {ValidationError} if any product fails validation
 */
export async function fetchProducts(): Promise<Product[]> {
  const response = await fetch('/api/products');

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data: unknown = await response.json();

  // Validate the response is an array
  if (!Array.isArray(data)) {
    throw new ValidationError(
      'API returned non-array response',
      data
    );
  }

  // Validate each product
  const products: Product[] = [];
  for (let i = 0; i < data.length; i++) {
    const item = data[i];
    if (!isProduct(item)) {
      throw new ValidationError(
        `Invalid product at index ${i}`,
        item
      );
    }
    products.push(item);
  }

  return products;
}

/**
 * Add a product to the shopping cart.
 * @returns The updated cart data
 */
export async function addToCart(
  productId: string,
  quantity: number
): Promise<{ success: boolean; cartTotal: number }> {
  const response = await fetch('/api/cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ productId, quantity })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data: unknown = await response.json();

  // Validate the response shape
  if (
    typeof data !== 'object' ||
    data === null ||
    typeof (data as any).success !== 'boolean' ||
    typeof (data as any).cartTotal !== 'number'
  ) {
    throw new ValidationError(
      'Invalid cart response from API',
      data
    );
  }

  return data as { success: boolean; cartTotal: number };
}

ValidationError: Invalid product at index 0
  at fetchProducts (api.ts:45)
  at ProductList.loadProducts (ProductList.tsx:12)

Invalid data: {
  "id": "123",
  "name": "Laptop",
  "image_url": "laptop.jpg",  // ← Wrong property name
  "price": 999.99,
  "inStock": true
}

// src/types/product.ts (Growing complexity)
export interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  imageUrl: string;
  inStock: boolean;
  onSale?: boolean;
  originalPrice?: number;
  // New fields added over time
  category: string;
  tags: string[];
  rating: number;
  reviewCount: number;
  dimensions?: {
    width: number;
    height: number;
    depth: number;
    weight: number;
  };
  variants?: Array<{
    id: string;
    name: string;
    price: number;
    inStock: boolean;
  }>;
}

// The type guard becomes a nightmare
export function isProduct(data: unknown): data is Product {
  if (typeof data !== 'object' || data === null) return false;
  const obj = data as Record<string, unknown>;

  // Basic fields
  if (typeof obj.id !== 'string') return false;
  if (typeof obj.name !== 'string') return false;
  if (typeof obj.description !== 'string') return false;
  if (typeof obj.price !== 'number') return false;
  if (typeof obj.imageUrl !== 'string') return false;
  if (typeof obj.inStock !== 'boolean') return false;

  // Optional fields
  if (obj.onSale !== undefined && typeof obj.onSale !== 'boolean') return false;
  if (obj.originalPrice !== undefined && typeof obj.originalPrice !== 'number') return false;

  // New fields
  if (typeof obj.category !== 'string') return false;
  if (!Array.isArray(obj.tags)) return false;
  if (!obj.tags.every(tag => typeof tag === 'string')) return false;
  if (typeof obj.rating !== 'number') return false;
  if (typeof obj.reviewCount !== 'number') return false;

  // Nested optional object
  if (obj.dimensions !== undefined) {
    if (typeof obj.dimensions !== 'object' || obj.dimensions === null) return false;
    const dims = obj.dimensions as Record<string, unknown>;
    if (typeof dims.width !== 'number') return false;
    if (typeof dims.height !== 'number') return false;
    if (typeof dims.depth !== 'number') return false;
    if (typeof dims.weight !== 'number') return false;
  }

  // Array of nested objects
  if (obj.variants !== undefined) {
    if (!Array.isArray(obj.variants)) return false;
    for (const variant of obj.variants) {
      if (typeof variant !== 'object' || variant === null) return false;
      const v = variant as Record<string, unknown>;
      if (typeof v.id !== 'string') return false;
      if (typeof v.name !== 'string') return false;
      if (typeof v.price !== 'number') return false;
      if (typeof v.inStock !== 'boolean') return false;
    }
  }

  return true;
}

export interface Product {
  // ... existing fields ...
  shippingWeight?: number;  // ← Added to interface
}

// Type guard NOT updated
export function isProduct(data: unknown): data is Product {
  // ... validation doesn't check shippingWeight ...
}

TypeError: shippingWeight.toFixed is not a function
  at calculateShipping (shipping.ts:23)
  at ShoppingCart.render (ShoppingCart.tsx:45)

npm install zod

// src/types/product.ts (Zod version)
import { z } from 'zod';

/**
 * Product schema - single source of truth for shape and validation.
 * TypeScript types are inferred automatically from this schema.
 */
export const ProductSchema = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string(),
  price: z.number().positive(),
  imageUrl: z.string().url(),
  inStock: z.boolean(),
  onSale: z.boolean().optional(),
  originalPrice: z.number().positive().optional(),
  category: z.string(),
  tags: z.array(z.string()),
  rating: z.number().min(0).max(5),
  reviewCount: z.number().int().nonnegative(),
  dimensions: z.object({
    width: z.number().positive(),
    height: z.number().positive(),
    depth: z.number().positive(),
    weight: z.number().positive(),
  }).optional(),
  variants: z.array(z.object({
    id: z.string(),
    name: z.string(),
    price: z.number().positive(),
    inStock: z.boolean(),
  })).optional(),
});

/**
 * TypeScript type inferred from the schema.
 * This is automatically kept in sync with the schema.
 */
export type Product = z.infer<typeof ProductSchema>;

/**
 * Validate unknown data against the Product schema.
 * Returns the validated data or throws a detailed error.
 */
export function validateProduct(data: unknown): Product {
  return ProductSchema.parse(data);
}

/**
 * Safe validation that returns a result object instead of throwing.
 * Use this when you want to handle validation errors gracefully.
 */
export function safeValidateProduct(data: unknown): 
  { success: true; data: Product } | { success: false; error: z.ZodError } {
  const result = ProductSchema.safeParse(data);
  return result;
}

// src/utils/api.ts (Zod version)
import { z } from 'zod';
import { Product, ProductSchema } from '../types/product';

/**
 * Fetch all products from the API.
 * Validates each product using Zod schema.
 */
export async function fetchProducts(): Promise<Product[]> {
  const response = await fetch('/api/products');

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data: unknown = await response.json();

  // Validate the entire response as an array of products
  const ProductArraySchema = z.array(ProductSchema);

  try {
    return ProductArraySchema.parse(data);
  } catch (error) {
    if (error instanceof z.ZodError) {
      console.error('Product validation failed:', error.format());
      throw new Error(`Invalid product data: ${error.message}`);
    }
    throw error;
  }
}

/**
 * Cart response schema
 */
const CartResponseSchema = z.object({
  success: z.boolean(),
  cartTotal: z.number().nonnegative(),
});

export async function addToCart(
  productId: string,
  quantity: number
): Promise<z.infer<typeof CartResponseSchema>> {
  const response = await fetch('/api/cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ productId, quantity })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data: unknown = await response.json();
  return CartResponseSchema.parse(data);
}

{
  "id": "123",
  "name": "Laptop",
  "price": "999.99",  // ← String instead of number
  "imageUrl": "laptop.jpg",
  "inStock": true,
  "category": "electronics",
  "tags": ["laptop", "computer"],
  "rating": 4.5,
  "reviewCount": 42
}

Product validation failed: {
  price: {
    _errors: ['Expected number, received string']
  }
}

Error: Invalid product data: [
  {
    "code": "invalid_type",
    "expected": "number",
    "received": "string",
    "path": ["price"],
    "message": "Expected number, received string"
  }
]

{
  "id": "123",
  "name": "Laptop",
  "price": 999.99,
  // ← Missing imageUrl
  "inStock": true,
  "category": "electronics",
  "tags": ["laptop"],
  "rating": 4.5,
  "reviewCount": 42
}

Product validation failed: {
  imageUrl: {
    _errors: ['Required']
  }
}

Error: Invalid product data: [
  {
    "code": "invalid_type",
    "expected": "string",
    "received": "undefined",
    "path": ["imageUrl"],
    "message": "Required"
  }
]

{
  "id": "123",
  "name": "Laptop",
  "price": 999.99,
  "imageUrl": "not-a-url",  // ← Invalid URL
  "inStock": true,
  "category": "electronics",
  "tags": ["laptop"],
  "rating": 4.5,
  "reviewCount": 42
}

Product validation failed: {
  imageUrl: {
    _errors: ['Invalid url']
  }
}

// src/types/product.ts (Advanced Zod patterns)
import { z } from 'zod';

/**
 * Product schema with transformations and custom validation
 */
export const ProductSchema = z.object({
  id: z.string(),
  name: z.string().min(1, "Product name cannot be empty"),
  description: z.string(),

  // Transform: API returns price in cents, we want dollars
  price: z.number().int().positive()
    .transform(cents => cents / 100),

  imageUrl: z.string().url(),
  inStock: z.boolean(),
  onSale: z.boolean().optional(),

  // Transform: API returns price in cents
  originalPrice: z.number().int().positive()
    .transform(cents => cents / 100)
    .optional(),

  category: z.string(),
  tags: z.array(z.string()),

  // Constrain rating to valid range
  rating: z.number().min(0).max(5),
  reviewCount: z.number().int().nonnegative(),

  dimensions: z.object({
    width: z.number().positive(),
    height: z.number().positive(),
    depth: z.number().positive(),
    weight: z.number().positive(),
  }).optional(),

  variants: z.array(z.object({
    id: z.string(),
    name: z.string(),
    price: z.number().int().positive()
      .transform(cents => cents / 100),
    inStock: z.boolean(),
  })).optional(),
})
  // Custom validation: if onSale is true, originalPrice must exist and be greater than price
  .refine(
    (data) => {
      if (data.onSale) {
        return data.originalPrice !== undefined && data.originalPrice > data.price;
      }
      return true;
    },
    {
      message: "When onSale is true, originalPrice must be greater than price",
      path: ["originalPrice"],
    }
  );

export type Product = z.infer<typeof ProductSchema>;

/**
 * API v1 schema - older API version with different field names
 */
export const ProductSchemaV1 = z.object({
  product_id: z.string(),
  product_name: z.string(),
  price_cents: z.number().int().positive(),
  image_url: z.string().url(),
  in_stock: z.boolean(),
  // ... other fields
})
  // Transform to match our internal Product type
  .transform((data) => ({
    id: data.product_id,
    name: data.product_name,
    price: data.price_cents / 100,
    imageUrl: data.image_url,
    inStock: data.in_stock,
    // ... map other fields
  }));

/**
 * Union type for handling multiple API versions
 */
export const ProductSchemaAnyVersion = z.union([
  ProductSchema,
  ProductSchemaV1,
]);

{
  "id": "123",
  "name": "Laptop",
  "price": 99999,  // ← 999.99 dollars in cents
  "imageUrl": "https://example.com/laptop.jpg",
  "inStock": true,
  "category": "electronics",
  "tags": ["laptop"],
  "rating": 4.5,
  "reviewCount": 42
}

const product = ProductSchema.parse(apiData);
console.log(product.price);  // 999.99 (transformed from cents)

{
  "id": "123",
  "name": "Laptop",
  "price": 99999,
  "imageUrl": "https://example.com/laptop.jpg",
  "inStock": true,
  "onSale": true,
  "originalPrice": 99999,  // ← Same as price, should be higher
  "category": "electronics",
  "tags": ["laptop"],
  "rating": 4.5,
  "reviewCount": 42
}

Product validation failed: {
  originalPrice: {
    _errors: ['When onSale is true, originalPrice must be greater than price']
  }
}

{
  "product_id": "123",
  "product_name": "Laptop",
  "price_cents": 99999,
  "image_url": "https://example.com/laptop.jpg",
  "in_stock": true
}

const product = ProductSchemaAnyVersion.parse(oldApiData);
// Automatically transformed to match Product type
console.log(product.id);        // "123"
console.log(product.name);      // "Laptop"
console.log(product.price);     // 999.99
console.log(product.imageUrl);  // "https://example.com/laptop.jpg"

// src/utils/api.ts (Production-ready version)
import { z } from 'zod';
import { Product, ProductSchema } from '../types/product';

/**
 * API error types for structured error handling
 */
export class NetworkError extends Error {
  constructor(
    message: string,
    public readonly status: number,
    public readonly statusText: string
  ) {
    super(message);
    this.name = 'NetworkError';
  }
}

export class ValidationError extends Error {
  constructor(
    message: string,
    public readonly zodError: z.ZodError
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

/**
 * Result type for operations that can fail
 */
export type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

/**
 * Fetch products with structured error handling.
 * Returns a Result type instead of throwing.
 */
export async function fetchProducts(): Promise<Result<Product[], NetworkError | ValidationError>> {
  try {
    const response = await fetch('/api/products');

    if (!response.ok) {
      return {
        success: false,
        error: new NetworkError(
          `Failed to fetch products`,
          response.status,
          response.statusText
        ),
      };
    }

    const data: unknown = await response.json();
    const ProductArraySchema = z.array(ProductSchema);

    const result = ProductArraySchema.safeParse(data);

    if (!result.success) {
      return {
        success: false,
        error: new ValidationError(
          'Invalid product data from API',
          result.error
        ),
      };
    }

    return { success: true, data: result.data };

  } catch (error) {
    // Network error (fetch failed)
    return {
      success: false,
      error: new NetworkError(
        error instanceof Error ? error.message : 'Unknown network error',
        0,
        'Network request failed'
      ),
    };
  }
}

/**
 * Add to cart with structured error handling
 */
const CartResponseSchema = z.object({
  success: z.boolean(),
  cartTotal: z.number().nonnegative(),
  itemCount: z.number().int().nonnegative(),
});

type CartResponse = z.infer<typeof CartResponseSchema>;

export async function addToCart(
  productId: string,
  quantity: number
): Promise<Result<CartResponse, NetworkError | ValidationError>> {
  try {
    const response = await fetch('/api/cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId, quantity })
    });

    if (!response.ok) {
      return {
        success: false,
        error: new NetworkError(
          'Failed to add to cart',
          response.status,
          response.statusText
        ),
      };
    }

    const data: unknown = await response.json();
    const result = CartResponseSchema.safeParse(data);

    if (!result.success) {
      return {
        success: false,
        error: new ValidationError(
          'Invalid cart response from API',
          result.error
        ),
      };
    }

    return { success: true, data: result.data };

  } catch (error) {
    return {
      success: false,
      error: new NetworkError(
        error instanceof Error ? error.message : 'Unknown error',
        0,
        'Request failed'
      ),
    };
  }
}

// src/components/ProductList.tsx
import React, { useEffect, useState } from 'react';
import { fetchProducts, NetworkError, ValidationError } from '../utils/api';
import { Product } from '../types/product';
import { ProductCard } from './ProductCard';

export function ProductList() {
  const [products, setProducts] = useState<Product[]>([]);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function loadProducts() {
      setIsLoading(true);
      setError(null);

      const result = await fetchProducts();

      if (result.success) {
        setProducts(result.data);
      } else {
        // Handle different error types
        if (result.error instanceof NetworkError) {
          if (result.error.status === 404) {
            setError('Products not found. Please try again later.');
          } else if (result.error.status >= 500) {
            setError('Server error. Please try again later.');
          } else {
            setError('Failed to load products. Please check your connection.');
          }
        } else if (result.error instanceof ValidationError) {
          // Log detailed validation errors for debugging
          console.error('Validation error:', result.error.zodError.format());
          setError('Received invalid data from server. Please contact support.');
        } else {
          setError('An unexpected error occurred.');
        }
      }

      setIsLoading(false);
    }

    loadProducts();
  }, []);

  if (isLoading) {
    return <div className="loading">Loading products...</div>;
  }

  if (error) {
    return (
      <div className="error">
        <p>{error}</p>
        <button onClick={() => window.location.reload()}>
          Retry
        </button>
      </div>
    );
  }

  return (
    <div className="product-list">
      {products.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          onAddToCart={(p) => console.log('Add to cart:', p)}
        />
      ))}
    </div>
  );
}

npm install awesome-charts

Could not find a declaration file for module 'awesome-charts'.
'/node_modules/awesome-charts/index.js' implicitly has an 'any' type.

Try `npm i --save-dev @types/awesome-charts` if it exists or add a new
declaration (.d.ts) file containing `declare module 'awesome-charts';`

src/
├── components/
│   ├── AnalyticsDashboard.tsx   ← Our main component
│   ├── SalesChart.tsx            ← Uses charting library
│   └── DateRangePicker.tsx       ← Uses date library
├── utils/
│   └── analytics.js              ← Legacy utility (no types)
└── types/
    ├── awesome-charts.d.ts       ← We'll create this
    └── analytics.d.ts            ← We'll create this

npm install awesome-charts

// src/components/SalesChart.tsx (Attempt 1)
import React from 'react';
import { LineChart } from 'awesome-charts';  // ← Error

interface SalesChartProps {
  data: Array<{ date: string; sales: number }>;
}

export function SalesChart({ data }: SalesChartProps) {
  return (
    <LineChart
      data={data}
      xKey="date"
      yKey="sales"
      width={600}
      height={400}
    />
  );
}

src/components/SalesChart.tsx:2:10 - error TS7016:
Could not find a declaration file for module 'awesome-charts'.
'/node_modules/awesome-charts/index.js' implicitly has an 'any' type.

2 import { LineChart } from 'awesome-charts';
           ~~~~~~~~~~

Try `npm i --save-dev @types/awesome-charts` if it exists or add a new
declaration (.d.ts) file containing `declare module 'awesome-charts';`

npm install --save-dev @types/awesome-charts

// src/types/awesome-charts.d.ts

/**
 * Type definitions for awesome-charts
 * Project: https://github.com/example/awesome-charts
 * Definitions by: Your Name
 */

declare module 'awesome-charts' {
  import { ReactElement } from 'react';

  /**
   * Common props shared by all chart components
   */
  interface BaseChartProps {
    /** Chart width in pixels */
    width?: number;
    /** Chart height in pixels */
    height?: number;
    /** CSS class name */
    className?: string;
    /** Chart title */
    title?: string;
  }

  /**
   * Props for LineChart component
   */
  interface LineChartProps<T = any> extends BaseChartProps {
    /** Array of data points */
    data: T[];
    /** Key in data object for x-axis values */
    xKey: keyof T;
    /** Key in data object for y-axis values */
    yKey: keyof T;
    /** Line color (hex or CSS color name) */
    color?: string;
    /** Show data point markers */
    showMarkers?: boolean;
    /** Smooth line curves */
    smooth?: boolean;
  }

  /**
   * Line chart component
   */
  export function LineChart<T = any>(props: LineChartProps<T>): ReactElement;

  /**
   * Props for BarChart component
   */
  interface BarChartProps<T = any> extends BaseChartProps {
    data: T[];
    xKey: keyof T;
    yKey: keyof T;
    /** Bar color */
    color?: string;
    /** Horizontal bars instead of vertical */
    horizontal?: boolean;
  }

  /**
   * Bar chart component
   */
  export function BarChart<T = any>(props: BarChartProps<T>): ReactElement;

  /**
   * Props for PieChart component
   */
  interface PieChartProps<T = any> extends BaseChartProps {
    data: T[];
    /** Key for slice labels */
    labelKey: keyof T;
    /** Key for slice values */
    valueKey: keyof T;
    /** Show percentage labels */
    showPercentages?: boolean;
  }

  /**
   * Pie chart component
   */
  export function PieChart<T = any>(props: PieChartProps<T>): ReactElement;
}

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,

    // Tell TypeScript where to find custom type definitions
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "types": []
  },
  "include": ["src"]
}

// src/components/SalesChart.tsx (Working version)
import React from 'react';
import { LineChart } from 'awesome-charts';

interface SalesData {
  date: string;
  sales: number;
}

interface SalesChartProps {
  data: SalesData[];
}

export function SalesChart({ data }: SalesChartProps) {
  return (
    <LineChart<SalesData>
      data={data}
      xKey="date"        // ← TypeScript knows this must be a key of SalesData
      yKey="sales"       // ← TypeScript knows this must be a key of SalesData
      width={600}
      height={400}
      color="#3b82f6"
      showMarkers={true}
      smooth={true}
    />
  );
}

// This now produces TypeScript errors:
<LineChart<SalesData>
  data={data}
  xKey="datte"        // ← Error: "datte" is not a key of SalesData
  yKey="revenue"      // ← Error: "revenue" is not a key of SalesData
  invalidProp={true}  // ← Error: Property 'invalidProp' does not exist
/>

src/components/SalesChart.tsx:12:3 - error TS2322:
Type '"datte"' is not assignable to type '"date" | "sales"'.

12   xKey="datte"
     ~~~~

src/components/SalesChart.tsx:13:3 - error TS2322:
Type '"revenue"' is not assignable to type '"date" | "sales"'.

13   yKey="revenue"
     ~~~~

src/components/SalesChart.tsx:14:3 - error TS2353:
Object literal may only specify known properties, and 'invalidProp' does not exist in type 'LineChartProps<SalesData>'.

14   invalidProp={true}
     ~~~~~~~~~~~